Quarto

How to report and reproduce your findings

Uros Godnov

Quarto - introduction

  • Released in June 2022.
  • Open-source scientific and technical publishing system.
  • Facilitates the creation of dynamic, reproducible documents, presentations, and reports.
  • Aims to produce high-quality, publication-ready outputs.
  • Supports multiple programming languages including R, Python, and Julia.
  • Enhances the reproducibility of scientific research.
  • Allows embedding of source code in documents for transparency.

Historical development

  • Evolution of Computational Document Authoring:

    • Before Quarto, R Markdown was a popular tool in the data science community for creating dynamic, reproducible documents using R. Increasing Demand for Multi-Language Support:

    • As the data science field grew, there was a rising demand for tools that could support multiple programming languages (e.g., Python, Julia) alongside R. Integration with Jupyter Ecosystem:

  • Jupyter Notebooks gained popularity for interactive computing, creating a need for tools that could bridge R Markdown and Jupyter. Quarto’s Development:

  • Quarto was developed to meet these evolving needs, offering a more flexible and powerful platform. It extended the capabilities of R Markdown by integrating with the Jupyter ecosystem and supporting multiple languages.

Benefits

  • Enhanced Reproducibility in Scientific Research:

    • Facilitates the creation of documents where data, code, and narrative are closely intertwined.

    • Improves the transparency and verifiability of research findings.

  • Easy Collaboration Features:

    • Supports collaborative workflows, making it simpler for teams to work together on documents.

    • Version control friendly, integrates well with platforms like GitHub.

  • High-Quality Publishing Outputs:

    • Capable of generating documents in various formats including HTML, PDF, and Word.

    • Ensures professional-grade layout and typesetting for publication-ready outputs.

Components

  • YAML header
  • code chunks
  • text

YAML header - 1

  • Location and Structure:

    • At the top of the document, enclosed between --- lines.

    • Written in key-value pairs using YAML syntax.

  • Document Metadata:

    • Title, author, and date.

    • Additional info like keywords and abstract.

  • Format Specifications:

    • Determines output format (HTML, PDF, Word).

    • Customization options for each format.

  • Code Chunk Options:

    • Global settings for all code blocks.

    • Controls echo, warning, message, and error displays.

YAML header - 2

  • Table of Contents and Navigation:

    • Configuration of depth, appearance, and placement.

    • Section numbering enable/disable option.

  • Citations and Bibliography:

    • Settings for citation processing.

    • Bibliography file specification and style guide selection.

  • Language Settings:

    • Controls for multilingual document support.
  • Cross-Referencing and Linking:

    • Configuration for figure and table referencing.

    • Hyperlinking and URL management settings.

YAML - 3

Demo

  • create a new quarto document

  • replace the current YAML with this one:

---
title: "Learning Quarto"
date: "2024-01-01"
subtitle: "The power of Quarto"
author: "Jane Doe"
abstract: "Quarto is a powerful tool for data science. We love Quarto!"
format: 
    html:
      toc: true
      toc_float: true
      toc-location: left
      mainfont: cursive
      embed-resources: true
---
  • save and render document

Demo

  • add new header *Loading packages in the begining
  • create new code chunk:
library(tidyverse)
library(knitr)
library(gt)
  • render the document. Observe.

Executable Code

#| echo: true
#| fig-width: 10
#| fig-height: 4.5
library(ggplot2)
ggplot(mtcars, aes(hp, mpg, color = am)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")

Demo

  • in the existing quarto create a new code chunk
  • copy the following code:
#| echo: true
#| fig-width: 10
#| fig-height: 4.5
library(ggplot2)
ggplot(mtcars, aes(hp, mpg, color = am)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
  • render the document. What can you observe?
  • change the echo to false and render again.
  • in YAML header add:
execution:
    echo: false
  • render and observe. What changed?

Update snippets

  • go to Snippet
  • copy snippets to RStudio > Tools > Edit Code Snippets
  • use Shift + Tab to autocomplete

Column Layout - 1

Arrange content into columns of varying widths:

::: columns
::: {.column width="35%"}
#### Motor Trend Car Road Tests

The data was extracted from the 1974 Motor Trend US magazine, and comprises fuel consumption and 10 aspects of automobile design and performance for 32 automobiles.
:::

::: {.column width="3%"}
:::

::: {.column width="62%"}
::: {.cell}
::: {.cell-output-display}
|                  |  mpg| cyl| disp|  hp|    wt|
|:-----------------|----:|---:|----:|---:|-----:|
|Mazda RX4         | 21.0|   6|  160| 110| 2.620|
|Mazda RX4 Wag     | 21.0|   6|  160| 110| 2.875|
|Datsun 710        | 22.8|   4|  108|  93| 2.320|
|Hornet 4 Drive    | 21.4|   6|  258| 110| 3.215|
|Hornet Sportabout | 18.7|   8|  360| 175| 3.440|
|Valiant           | 18.1|   6|  225| 105| 3.460|
:::
:::
:::
:::

Column Layout - 2

Motor Trend Car Road Tests

The data was extracted from the 1974 Motor Trend US magazine, and comprises fuel consumption and 10 aspects of automobile design and performance for 32 automobiles.

mpg cyl disp hp wt
Mazda RX4 21.0 6 160 110 2.620
Mazda RX4 Wag 21.0 6 160 110 2.875
Datsun 710 22.8 4 108 93 2.320
Hornet 4 Drive 21.4 6 258 110 3.215
Hornet Sportabout 18.7 8 360 175 3.440
Valiant 18.1 6 225 105 3.460

Demo

  • to existing Quarto document add new header Columns
  • create 2 columns, with 50 % and 50 % width
  • in the first column add a code chunk:
airquality %>% 
   head() %>% 
   kable()
  • in the second column add a code chunk:
airquality %>% 
   head() %>% 
   gt()
  • render and observe

Important

  • displaying tables can be tricky
  • never just list a name of a dataframe
  • if dataframe is huge, rendering will take forever
  • always go with the packages that are meant to display tables
  • control the number of rows

Cross-referencing a table

  • label has to start with “tbl-”
#| label: tbl-airquality
#| tbl-cap: "The airquality in New York in 1973"

airquality %>% 
   head() %>% 
   gt()
  • in a code you have to reference a table with “@” prefix:
In the table @tbl-airquality we collected data for 5 months.

Demo

  • create a new header called Cross referencing a table.
  • copy the code from previous slide and the text under new header
  • render and observe

Cross-referencing a picture (plot)

  • label has to start with “fig-”
  • bug in quarto, it doesnt display title nor referencing part
#| label: fig-airquality
#| fig-cap: "Ozone vs. temp"

airquality %>% 
   dplyr::select(Ozone, Temp) %>% 
   ggplot(., aes(x=Temp, y=Ozone))+
   geom_point()

The chart @fig-airquality shows the relationship between Ozone and Temp.

Cross-referencing a inserted picture

  • name must begin with “#fig-” prefix
![kitten](mini/images/kitten-300-200.jpeg){#fig-kitten}


The kitten in the @fig-kitten is hungry.

Demo

  • in the current Quarto add header Cross referencing a figure.
  • find a picture online and cross-reference it
  • render and observe

Tabsets - 1

::: panel-tabset
### Plot

::: {.cell}
::: {.cell-output-display}
![](quarto_presentations_files/figure-revealjs/unnamed-chunk-4-1.png){width=960}
:::
:::

### Data


::: {.cell}
::: {.cell-output-display}
|                    |  mpg| cyl|  disp|  hp| drat|    wt|  qsec| vs| am| gear| carb|
|:-------------------|----:|---:|-----:|---:|----:|-----:|-----:|--:|--:|----:|----:|
|Mazda RX4           | 21.0|   6| 160.0| 110| 3.90| 2.620| 16.46|  0|  1|    4|    4|
|Mazda RX4 Wag       | 21.0|   6| 160.0| 110| 3.90| 2.875| 17.02|  0|  1|    4|    4|
|Datsun 710          | 22.8|   4| 108.0|  93| 3.85| 2.320| 18.61|  1|  1|    4|    1|
|Hornet 4 Drive      | 21.4|   6| 258.0| 110| 3.08| 3.215| 19.44|  1|  0|    3|    1|
|Hornet Sportabout   | 18.7|   8| 360.0| 175| 3.15| 3.440| 17.02|  0|  0|    3|    2|
|Valiant             | 18.1|   6| 225.0| 105| 2.76| 3.460| 20.22|  1|  0|    3|    1|
|Duster 360          | 14.3|   8| 360.0| 245| 3.21| 3.570| 15.84|  0|  0|    3|    4|
|Merc 240D           | 24.4|   4| 146.7|  62| 3.69| 3.190| 20.00|  1|  0|    4|    2|
|Merc 230            | 22.8|   4| 140.8|  95| 3.92| 3.150| 22.90|  1|  0|    4|    2|
|Merc 280            | 19.2|   6| 167.6| 123| 3.92| 3.440| 18.30|  1|  0|    4|    4|
|Merc 280C           | 17.8|   6| 167.6| 123| 3.92| 3.440| 18.90|  1|  0|    4|    4|
|Merc 450SE          | 16.4|   8| 275.8| 180| 3.07| 4.070| 17.40|  0|  0|    3|    3|
|Merc 450SL          | 17.3|   8| 275.8| 180| 3.07| 3.730| 17.60|  0|  0|    3|    3|
|Merc 450SLC         | 15.2|   8| 275.8| 180| 3.07| 3.780| 18.00|  0|  0|    3|    3|
|Cadillac Fleetwood  | 10.4|   8| 472.0| 205| 2.93| 5.250| 17.98|  0|  0|    3|    4|
|Lincoln Continental | 10.4|   8| 460.0| 215| 3.00| 5.424| 17.82|  0|  0|    3|    4|
|Chrysler Imperial   | 14.7|   8| 440.0| 230| 3.23| 5.345| 17.42|  0|  0|    3|    4|
|Fiat 128            | 32.4|   4|  78.7|  66| 4.08| 2.200| 19.47|  1|  1|    4|    1|
|Honda Civic         | 30.4|   4|  75.7|  52| 4.93| 1.615| 18.52|  1|  1|    4|    2|
|Toyota Corolla      | 33.9|   4|  71.1|  65| 4.22| 1.835| 19.90|  1|  1|    4|    1|
|Toyota Corona       | 21.5|   4| 120.1|  97| 3.70| 2.465| 20.01|  1|  0|    3|    1|
|Dodge Challenger    | 15.5|   8| 318.0| 150| 2.76| 3.520| 16.87|  0|  0|    3|    2|
|AMC Javelin         | 15.2|   8| 304.0| 150| 3.15| 3.435| 17.30|  0|  0|    3|    2|
|Camaro Z28          | 13.3|   8| 350.0| 245| 3.73| 3.840| 15.41|  0|  0|    3|    4|
|Pontiac Firebird    | 19.2|   8| 400.0| 175| 3.08| 3.845| 17.05|  0|  0|    3|    2|
|Fiat X1-9           | 27.3|   4|  79.0|  66| 4.08| 1.935| 18.90|  1|  1|    4|    1|
|Porsche 914-2       | 26.0|   4| 120.3|  91| 4.43| 2.140| 16.70|  0|  1|    5|    2|
|Lotus Europa        | 30.4|   4|  95.1| 113| 3.77| 1.513| 16.90|  1|  1|    5|    2|
|Ford Pantera L      | 15.8|   8| 351.0| 264| 4.22| 3.170| 14.50|  0|  1|    5|    4|
|Ferrari Dino        | 19.7|   6| 145.0| 175| 3.62| 2.770| 15.50|  0|  1|    5|    6|
|Maserati Bora       | 15.0|   8| 301.0| 335| 3.54| 3.570| 14.60|  0|  1|    5|    8|
|Volvo 142E          | 21.4|   4| 121.0| 109| 4.11| 2.780| 18.60|  1|  1|    4|    2|
:::
:::

:::

Tabsets - 2

mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258.0 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360.0 175 3.15 3.440 17.02 0 0 3 2
Valiant 18.1 6 225.0 105 2.76 3.460 20.22 1 0 3 1
Duster 360 14.3 8 360.0 245 3.21 3.570 15.84 0 0 3 4
Merc 240D 24.4 4 146.7 62 3.69 3.190 20.00 1 0 4 2
Merc 230 22.8 4 140.8 95 3.92 3.150 22.90 1 0 4 2
Merc 280 19.2 6 167.6 123 3.92 3.440 18.30 1 0 4 4
Merc 280C 17.8 6 167.6 123 3.92 3.440 18.90 1 0 4 4
Merc 450SE 16.4 8 275.8 180 3.07 4.070 17.40 0 0 3 3
Merc 450SL 17.3 8 275.8 180 3.07 3.730 17.60 0 0 3 3
Merc 450SLC 15.2 8 275.8 180 3.07 3.780 18.00 0 0 3 3
Cadillac Fleetwood 10.4 8 472.0 205 2.93 5.250 17.98 0 0 3 4
Lincoln Continental 10.4 8 460.0 215 3.00 5.424 17.82 0 0 3 4
Chrysler Imperial 14.7 8 440.0 230 3.23 5.345 17.42 0 0 3 4
Fiat 128 32.4 4 78.7 66 4.08 2.200 19.47 1 1 4 1
Honda Civic 30.4 4 75.7 52 4.93 1.615 18.52 1 1 4 2
Toyota Corolla 33.9 4 71.1 65 4.22 1.835 19.90 1 1 4 1
Toyota Corona 21.5 4 120.1 97 3.70 2.465 20.01 1 0 3 1
Dodge Challenger 15.5 8 318.0 150 2.76 3.520 16.87 0 0 3 2
AMC Javelin 15.2 8 304.0 150 3.15 3.435 17.30 0 0 3 2
Camaro Z28 13.3 8 350.0 245 3.73 3.840 15.41 0 0 3 4
Pontiac Firebird 19.2 8 400.0 175 3.08 3.845 17.05 0 0 3 2
Fiat X1-9 27.3 4 79.0 66 4.08 1.935 18.90 1 1 4 1
Porsche 914-2 26.0 4 120.3 91 4.43 2.140 16.70 0 1 5 2
Lotus Europa 30.4 4 95.1 113 3.77 1.513 16.90 1 1 5 2
Ford Pantera L 15.8 8 351.0 264 4.22 3.170 14.50 0 1 5 4
Ferrari Dino 19.7 6 145.0 175 3.62 2.770 15.50 0 1 5 6
Maserati Bora 15.0 8 301.0 335 3.54 3.570 14.60 0 1 5 8
Volvo 142E 21.4 4 121.0 109 4.11 2.780 18.60 1 1 4 2

Demo

  • add mtcars header to quarto document
  • create tabset panel with 3 tabsets
  • name them dummy1, mtcars, dummy2
  • create a chunk for the second tabset and add:
   mtcars %>% 
        head() %>% 
        gt()

Callout bloks - 1

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::

::: {.callout-tip}
## Tip with Title

This is an example of a callout with a title.
:::

::: {.callout-warning}
## Standardization

This is an example of a warning.
:::

Callout bloks - 2

Note

Note that there are five types of callouts, including: note, warning, important, tip, and caution.

Tip with Title

This is an example of a callout with a title.

Standardization

This is an example of a warning.

Demo

  • add new Callout warning after loading packages. State the document is meant only for learning purposes.

Interactive Slides

Include Jupyter widgets and htmlwidgets in your presentations

Cache

  • large chunks –> use cache
#| cache: true

Sys.sleep(5)
  • add new header Cache.
  • copy above code to the new chunk
  • render, observe
  • render again and observe